20.16 Keyboard Macros

A keyboard macro is a canned sequence of input events that can be considered a command and made the definition of a key. The Lisp representation of a keyboard macro is a string or vector containing the events. Don’t confuse keyboard macros with Lisp macros (see Macros).

Function: execute-kbd-macro kbdmacro &optional count loopfunc

This function executes kbdmacro as a sequence of events. If kbdmacro is a string or vector, then the events in it are executed exactly as if they had been input by the user. The sequence is not expected to be a single key sequence; normally a keyboard macro definition consists of several key sequences concatenated.

If kbdmacro is a symbol, then its function definition is used in place of kbdmacro. If that is another symbol, this process repeats. Eventually the result should be a string or vector. If the result is not a symbol, string, or vector, an error is signaled.

The argument count is a repeat count; kbdmacro is executed that many times. If count is omitted or nil, kbdmacro is executed once. If it is 0, kbdmacro is executed over and over until it encounters an error or a failing search.

If loopfunc is non-nil, it is a function that is called, without arguments, prior to each iteration of the macro. If loopfunc returns nil, then this stops execution of the macro.

See Reading One Event, for an example of using execute-kbd-macro.

Variable: executing-kbd-macro

This variable contains the string or vector that defines the keyboard macro that is currently executing. It is nil if no macro is currently executing. A command can test this variable so as to behave differently when run from an executing macro. Do not set this variable yourself.

Variable: defining-kbd-macro

This variable is non-nil if and only if a keyboard macro is being defined. A command can test this variable so as to behave differently while a macro is being defined. The value is append while appending to the definition of an existing macro. The commands start-kbd-macro, kmacro-start-macro and end-kbd-macro set this variable—do not set it yourself.

The variable is always local to the current terminal and cannot be buffer-local. See Multiple Terminals.

Variable: last-kbd-macro

This variable is the definition of the most recently defined keyboard macro. Its value is a string or vector, or nil.

The variable is always local to the current terminal and cannot be buffer-local. See Multiple Terminals.

Variable: kbd-macro-termination-hook

This normal hook is run when a keyboard macro terminates, regardless of what caused it to terminate (reaching the macro end or an error which ended the macro prematurely).